



                         The GRAAL Script Editor
                         =======================


Introduction
------------

This is a neat little (well, not that small, actually) editor, making life
in the GRAAL script-writing lane much easier than it otherwise would be.

At first, you may find the concept behind it all slightly confusing. While
other "user-friendly" games development systems opt for point-and-click
control of everything, GRAAL is still only made up of ASCII scripts that
can be created using any text editor. The GRAAL editor is just a helping
hand, making entry of some of the trickier statements a lot easier. The end
result is the same as you would get with any other editor, though - ASCII
script files with lists of GRAAL statements and commands.

Why, then, should you use the GRAAL editor, and not any other editor?

* It handles multiple scripts in multiple windows with easy switching, 
  copying and pasting between them.

* It gives help on the syntax of statements and commands.

* It performs basic syntax checking. It doesn't mean you won't get some
  run-time errors in GRAAL, but not the really stupid ones caused by
  obvious typing errors.

* It simplifies coding and editing of object, image, exit, and floor
  related statements.

* Although many features are GRAAL-related, it is perfectly possible to use
  this editor to edit any kind of ASCII text file. You will probably find
  it a good alternative. Enjoy!

* It handles files up to 5000 lines long. (If you have GRAAL scripts that
  long, you are probably in need of professional help :-)




System Requirements
-------------------

This editor needs Workbench 2.0 or better to work.

On AGA machines, it "clones" your Workbench setting, so if you have a
hi-res Workbench, it uses a hi-res screen; with a Productivity Workbench, it
opens in Productivity mode... you get the picture. Just make sure that your
Workbench is at least 640 pixels wide, and everything should operate
smoothly. On non-AGA machines, a normal hi-res, non-interlaced screen is
used.

Also note that the editor must be placed in your game development library
on your hard disk for all file fetching routines to operate without problems.



Known bugs
----------

* Sometimes when you re-size a window other than the currently active, the
  display in that window becomes corrupted. Put the window in front and
  activate before re-sizing, this should help you avoid any problems. In
  most cases, you are better off using the "Select Window" functions to
  switch between windows, anyway.

* Marking a block that extends over the last actual text line in a file may
  cause problems. Avoid.

* The ASL file requester which so conveniently filters out files you do not
  want to see only works on AGA machines - non-AGA machines use the Blitz2
  standard file requester. (This is because I couldn't get the ASL requester
  to open on the GRAAL Editor screen on WB 2.05 - it kept popping up on the
  Workbench screen no matter what, which was very irritating to say the
  least.)

* .scene and .ptrn file templates have some commented-out statements in
  them, indicating these statements can optionally included in yous scripts.
  As you know if you have read the GRAAL documentation, .scene and .ptrn
  files do not contain statements at all, so thing is plain wrong. Sorry
  'bout that. Will fix this in the next release!




                         WORKING WITH THE EDITOR
                         =======================



Creating a New Script
---------------------

Since the editor expects to be placed in your GRAAL development directory, 
it checks for a graal.main file in the current directory at start-up -
without such a file, you don't really have much of a development environment!

If there is no graal.main file, the editor asks if one should be created.
If you answer "yes", a template for such a script will be created in the
editing window (which makes up the main part of the editor display).

You can also use the "New" option in the "Project" menu to create a new
file. The "New" option has six suboptions. The first one, "empty", just
opens a new, empty editing window on top of the first one. The editor
handles up to ten script windows simultaneously, and you can switch
between them quite easily with the "Select Window" option in the "Edit" menu
(or <Amiga>+<W>).

The next three suboptions, "graal.main", ".room", and ".section" opens a
new window and places a template for the selected script type there. The
last two suboptions are for ".scene" and ".ptrn" scripts respectively, and
do not have templates.

Note the file name stated in the top border of the window - for all script
types, the file name is (partly) created when you select "New". However, 
.room, .section, .scene, and .ptrn files are not numbered, so you need
to supply the correct number before the type suffix. This means the first
time you save the file, use the "Save As" option in the "Project" menu.
Once the file name is correct, you can use the "Save" option instead.



Loading Existing Scripts
------------------------

Just like the "New" option, the "Load" option (also in the "Project" menu)
has a number of suboptions. The only thing they do is make the file
requester show only the correctly named files. For example, the ".room"
suboption only brings up a list of all ".room" files, making the search
for the correct script quicker and easier. The "general" suboption shows
all the files in the directory.

Most of the time, you probably want to open a script in a new window, which
is why you should use the "Open & Load" option instead. In this case, the
suboptions have keyboard shortcuts (<amiga>+<3-8>). Learn to use them, as
this is the quickest way to open scripts.



The Templates and the Syntax Checker
------------------------------------

Some statements in the templates have some suggested parameters already
filled in. In most cases there is no point in giving a suggestion, though, 
because the correct parameters are very much up to yourself. You can see
this quite easily: Create a new graal.main script, making the editor give
you a graal.main template. Now press the button marked "Syntax". This will
make the editor check the script in the current window for syntax errors, 
and it will not be very long before it comes upon a statement with no
parameter filled in. It then displays an error message telling you about
the problem, and it also marks the statement where the error occurs.

The syntax checker is a great help, but it does not find every possible
error. This is what it does:

* The names of all statements are checked.

* It checks that all mandatory statements are in place. However, note that
  some statements may depend on others to work, and this is not checked by
  this function. Be particularly careful with graphics, and make sure the
  correct CLPART: statement is in effect in every situation requiring
  CLPART pictures!

* The number of parameters for all statements are checked (except for
  statements with a variable number of parameters).

* For all parameters that may consist of conditions, commands, or both, 
  the name of each condition and command is checked.

If any error is found, the offending statement / command is highlighted, 
and the nature of the error is shown in a requester as described above.

Note: The syntax checker uses the file name suffix to determine what
statements and commands are allowed - so it can only be used in files
following the GRAAL naming conventions.

All this should make development a little less frustrating. However, GRAAL
itself checks a lot of other stuff too, and will still throw runtime errors
at you from time to time. Further improvements will probably appear over
time.



Syntax Help
-----------

If you place the cursor on a statement or command word and press the HELP
key, a simple syntax help is shown in the screen title bar. Explanations:

[...]         This part is optional

UPPERCASE     This parameter must be typed as shown here.

...|...       A separator separating alternative options for the parameter.

{...}         This parameter is repetitive. E.g., {command|condition} means
              any number of GRAAL commands and/or conditions, separated
              by semi-colons, may be placed here.

...|list      This parameter may be list of values like the one on the
              left hand side of the | character - the values in the list
              must be separated by | characters.

Note that after having run the syntax checker, the cursor is placed on the
failing statement or command, which means you can press <help> immediately
for further information.

Also note that like the syntax checker, the help function uses the file
name suffix to determine what statements and commands are allowed - so it
can only be used in files following the GRAAL naming conventions.

If further help is required, refer to the graal.guide on-line reference.



Normal Editing Functions
------------------------

I will not bother you too much about the functions that you are likely
to encounter in any text editor. You should find the find & replace options, 
and the other options of the "Edit" menu, quite adequate for the job at hand.

Just a few words about useful keyboard keys:

<shift>+<down arrow>
<shift>+<up arrow>      These keys scrolls the script one page at a time.

<shift>+<right arrow>   Moves the cursor past the last character of the line.

<shift>+<left arrow>    Moves the cursor to the beginning of the line.

<control>+<right arrow> Moves to the next semi-colon of the line; that is, 
                        to the next GRAAL statement parameter.

<esc>                   Close the current window.

<enter>                 Exit a string gadget (for example, in the Find
                        window), or carry out a function (for example, 
                        "Find" in the find window, once the cursor is not
                        in a string gadget anymore).

Other available shortcut keys are all listed in the menus.



Marking Text Using the Mouse
----------------------------

Apart from marking text blocks with <amiga>+<1> and <amiga>+<2>, you can use
the mouse:

1   Click the first character of the block.

2   Hold down a <shift> key and click the character immediately to the right
    of the last character of the block. (Clicking the first character of a
    will mark the entire previous line.)



The Status Bar
--------------

Some useful bits of information are shown in the "status bar" immediately
above the editing windows:

1   Cursor row (r) and column (c) position.

2   Insert (I) or overstrike (O) write mode.

3   Number of changes made since the last save. Note that some "big"
    operations, like inserting a block of text, only count as one change
    each!

4   Time. The clock is only updated when you do something in the editor, 
    like moving the cursor.



Switching between Windows
-------------------------

When writing GRAAL scripts, you very often need to make changes to two or
more script files almost simultaneously. Fortunately, the GRAAL editor
really excels at this.

Use <amiga>+<w> to open a window containing a list of all currently open
editing windows and their contents. In addition, all windows where unsaved
changes exist are marked with an asterisk ( * ) before the window number.

Click on any name in the list, and that window will become active and placed
on top of the other windows. You can also use the cursor keys and select
a window with the <enter> key. In fact, the GRAAL text editing functions
have been designed to make as little use of the mouse as possible - the
keyboard is much faster once you get accustomed to using all shortcut keys.

If you need to view more than one script at the same time, just resize the
editing windows and place them next to each other - nothing could be simpler.
(Though I must confess I don't use this much myself - window switching is
so much easier!)



                            THE STATEMENT EDITORS
                            =====================

The Statement Editors are a bunch of functions helping you edit some of the
most complex statements in the GRAAL language.



The Object Editor
-----------------

Let's start with the most complex of all, the OBJECT:/ROOMOBJ:/SECTIONOBJ:
statement. This is available both from the "Object" button and the "Edit
Object" option in the "GRAAL" menu.

What happens when you choose the option depends on whether the cursor
was placed on an OBJECT: statement line when it was invoked. If so, 
the parameters of that statement is edited: Otherwise, GRAAL will assume
that you want to create a new object. This means once you save the edits, 
this will create a new OBJECT: statement line at the cursor position.

Note: The editor is clever enough to recognise whether you are in a .main, 
.room, or .section script, and will adjust to an OBJECT:, ROOMOBJ:, or
SECTIONOBJ: accordingly. The same goes for the other editors handling
statements which are differently named depending on the script type in
which they appear.

Okay, what happens when we call upon the object editor, then? First, we
get a new window, displaying all the object parameters in a much nicer
way than the ordinary statement syntax. Most are represented by string
gadgets which must be properly filled in, a few with fixed options are
represented by text cycle gadgets - click on one of these to cycle through
the possible settings. For example, "Visible:" just switches between
"yes" and "no".

If you press the <OK> button, the object editor window closes, and:

* If the cursor was on an existing OBJECT: statement, this line will be
  replaced with the updated version.

* Otherwise, a new statement line will be inserted at the cursor position.

If you press <Cancel>, nothing will happen to the script.



Editing the Object Position On-screen
-------------------------------------

The trickiest part of GRAAL coding is getting on-screen coordinates right.
In the object editor, there is a < <-Edit > button next to the string
gadgets dealing with the object position and appearance. Press this, and
you will be able to place the object correctly against the background
picture using the mouse.

To achieve this, the editor will ask for two files: First, it asks you to
name a .room file. This is because it is about to create a list of all
available images that you could possibly want to use for the object, and
it need information about the .room file to know which BOB images to load.

Next, it asks for the name of the background picture against which you want
to place the object. For example, if you are editing a ROOMOBJ: in room
1, the two files would probably be "1.room" and "1BG.IFF" (if you follow
the naming standards of my example adventure).

By now, the background picture should have appeared on screen. If you are
editing a new statement, the first image fount in the graal.main file is
displayed in the bottom left corner of the picture.

Hold the left mouse button down and drag the mouse - the image will follow.
Press the down arrow key - the image shown will change and "cycle through"
all the images found in the graal.main, selected .room and .section scripts.
Simply select the proper image and place it in the proper place in the
picture.

If the background picture is wider than the screen, you can scroll it with
the left and right arrow keys.

Press <enter> if you wish to save the position, or <esc> to cancel the
operation.

If you were editing a new statement, or an old statement which defined
the object image as a single BOB image (not a pattern or an animation
sequence), both the object position and the object image specification will
be updated. When the statement contains an animation sequence or pattern, 
only the position is updated, so as not to spoil any earlier work you may
have put into the specification of the image/animation/pattern.



The BOB Image Editor
--------------------

The rest of the editors don't have their own fancy "parameter windows" like
the Object Editor - they simply don't have enough parameters to justify
that. Instead, they only help with the graphical side of things, much like
the "edit position" part of the Object Editor.

To illustrate this, the BOB Image Editor is next. It only edits five of the
eight parameters in BOBS:, ROOMBOBS: and SECTIONBOBS: statements: x, y, 
width, height, and x-offset. If you create a new statement with the editor, 
you must make sure to complete the statement by filling in the other three
parameters correctly yourself.

The BOB Image Editor also needs the name of a picture file - this is the
"clipart" picture from which the BOB images should be cut out. Before
you invoke the editor, select the proper file name using the "Change Picture"
option in the "GRAAL" menu: All editors will continue to use the same
picture file unless this option is used to change the file name.

Once the clipart picture is shown, click and drag the mouse. You should see
a small square move across the picture from the upper left corner: This is
the cut-out frame. Now release the button, select a point in the bottom right
corner of the frame, and drag again. This will re-size the frame. All you
have to do now is place the frame around the image you want, and adjust the
size. Save the information with the <enter> key, which updates, the script.

If the ...BOBS: statement says that more than one image should be cut out
(which is specified in the first parameter), a number of horisontally
aligned frames, equal to the number of images being cut out, are shown
agains the clipart picture. Use the leftmost frame to frame the first image.
Then, you can adjust the spacing between the frames with the up and down
arrow keys until each frame is properly placed around its image.



The Exit Editor
---------------

The Exit Editor works much like the BOB Image Editor. Remember that you want
to edit against the proper background picture, so switch to the proper file
with <Change Picture> first!

You will see all exits in the room marked as white rectangles, each numbered
with the exit number. All except the one on which the cursor was placed -
this is shown as a resizable, movable frame just like the one in the BOB
Image editor. Place it and re-size it using the mouse.

You can also specify the exit point - This is the point which the character
will move to when the MEXIT command is given. It is initially shown as a
small cross-hair in the bottom left corner of the picture. Point to the
cross-hair, and drag it to where you want the exit point.

As always, if the picture is larger than the screen, use the left and right
arrow keys to move around.



The Floor Editor
----------------

VERY similar to the Exit Editor, this one - shows all the floors and their
numbers.



The Coordinate Editor
---------------------

There are many other statements and commands requiring object coordinates
at some point. This simple little editor does the trick - it does not
produce full-blown statements or commands, it just inserts x and y
coordinates, separated by commas, at the current cursor position. It allows
you to position any of the available images just like in the Object Editor, 
switching the image used with the up and down arrow keys. Neat or what?
Don't leave home without it!



                             COPYRIGHT INFO
                             ==============

The GRAAL Script Editor 1.0 is part of the unregistered GRAAL 1.0 shareware
package. It has been my first project in Blitz 2 Basic and can be used for
any purpose free of charge.

Has someone come up with an Amal emulation library for Blitz yet? If so, I
will spend the next year converting GRAAL to Blitz. 256-colour city, here
we come! ( -not- :)
